Architecture: Objects

The objects provided by the SDK are arranged in a containment hierarchy. Beginning with the Application object, you can get other objects "contained" by the Application, such as the Drawing objects that the application manages. Below are listed some of the basic objects and their responsibilities. For a complete reference to the hierarchy, consult the object model API reference page.

The Application Object

The Application object represents the currently running TurboCAD v4 session. The Application exists primarily to manage one or more Drawing objects, as well as make available services and objects to the Drawings. Some of the other objects accessible from the Application object are:

NamedColor	Entries in a look-up table for specifying colors in a palette by name, rather than RGB or HSV value
RegenMethod	Extensions to TurboCAD's primitive graphic types
Filter	Allow for opening and saving of drawing data in a variety of file formats
Tool	Allow for the creation of new user interface procedures
User interface	Allow for the runtime customization of TurboCAD's user interface (Menus, Toolbars, etc.)
Application Property	Allow you to change the values of session-wide attributes
AppOptions	Controls some of the session-wide behavior of TurboCAD v4
System	Provides the programmer with information about the current state of the operating system

The Drawing Object

The Drawing object represents the document in TurboCAD v4, that is, a unit that can be saved to persistent storage. Drawings contain Graphics collections that allow you to manipulation all the graphical entities (Graphic objects) in the drawing.

The graphics in the drawing can be grouped in other pseudo-collections:

Selection	Pseudo-collection of references to all the graphical entities in the drawing with a selection attribute
Arbitrary Graphic Set	Pseudo-collection of references to Graphic objects in the drawing

Other aspects of Drawings are manipulated through specific objects in the model:

Layer	Control the grouping and visibility of Graphics
LineStyle	Control the different line types available in a drawing
BrushStyle	Control the different fill types available in a drawing
Drawing Property	Provide access to drawing-wide attributes
DwgOptions	Sets some of the drawing-specific behavior

Graphic Objects

Graphic objects can be created independent of a drawing, and added to a drawing's Graphics collection at a later time.

Graphic objects are organized in a hierarchy.

• Every Graphic object has a Graphics collection that child Graphic objects can be added to
• Graphics can be permanent or cosmetic
  • Cosmetic graphics are children of top-level graphics and are destroyed and rebuilt every time the geometry or properties of the top-level graphic is modified.

Other attributes of the graphic are Editable...

A Graphic object's geometry is described by the Vertex objects in its Vertices collection.

Vertex Objects

Vertex objects can exist outside of a Graphic object's Vertices collection.

Vertex attributes:

• PenDown
• Editable
• Linkable
• Snappable

Don't add or delete vertices in Arc, Text, OLEObject or RegenMethod graphics. Manipulating vertices in a Graphic object can cause the RegenMethod to change the appearance of the graphic.

Accessing Named Object Properties: The Property Object

In addition to calling methods on the objects in the TurboCAD SDK, a common way to program is to get and set named, customizable, object properties. For the Application, Drawing and Graphic objects, these are exposed by a Property object, contained in a Properties collection that can be accessed by the parent object. For example in order to change the pen color of a Graphic object, neither a PenColor property nor a SetPenColor method is provided. Instead a object that represents the PenColor property is obtained by indexing the name "PenColor" in the Graphic's Properties collection, and then setting its value. This allows for the addition of a large number of properties to these objects without cluttering the interface of the parent object.

Properties specified by Property objects can be built in, provided by the the TurboCAD system, or custom, added by the user at runtime. The Property objects contained by the parent objects are classified as follows:

• Application properties: built in only.
• Drawing properties: built in only.
• Graphic properties: built in and custom.

In addition, a slightly different interface is provided for Microsoft Office standard Document properties, such as Author, Keywords, etc. that can be browsed by Microsoft Office-compatible applications.

A deeper discussion on Property objects can be found here.

The Viewport Object

There are two kinds of Viewport objects, built-in and custom. 

• Built-in viewports are provided by the TurboCAD application (local server), and are the client areas of the MDI windows opened for each drawing.
• Custom viewports are created only through the SDK, either in the local or in-process server, through the Viewports.Add method.

Custom viewports can be destroyed via the Viewport.Delete method.

Drawing in a Viewport

Viewports allow four different methods of drawing:

• Drawing to a window's client area
  When creating a custom viewport, specify a window handle (HWND) in the HWND argument to Viewports.Add. In the window's WM_PAINT message, call Viewport.Refresh. TurboCAD's built-in viewports handle this refreshing automatically.
• Drawing to a non-window DC (i.e. printer or memory DC)
  When creating the viewport, specify a device context handle (HDC) in the DC argument to Viewports.Add. You force drawing to the DC by calling Viewport.Refresh.
• Creating a bitmap image
  Any viewport object can be used to make a bitmap image. Use Viewport.OpenBitmap to indicate that subsequent drawing to this viewport will go to a memory device context. OpenBitmap returns an HDC handle, which can be passed to Win32 GDI functions. Draw onto the memory device context by calling Viewport.Refresh. Call Viewport.CloseBitmap to release the memory device context and return an HGLOBAL handle to a device-independent bitmap (DIB).
• Creating a metafile image
  Any viewport object can be used to make a metafile image. Use Viewport.OpenBitmap to indicate that subsequent drawing to this viewport will go to a metafile device context. OpenMetafile returns an HDC handle, which can be passed to Win32 GDI functions. Draw onto the metafile device context by calling Viewport.Refresh. Call Viewport.CloseBitmap to release the metafile device context and return an HMETAFILE handle.

Only one type of special drawing (bitmap or metafile) can be done between calls to OpenBitmap and CloseBitmap, or OpenMetafile and CloseMetafile. Make sure that every OpenBitmap/Metafile call has a corresponding CloseBitmap/Metafile call.

The Selection Object

The Selection collection represents a special collection of graphic objects in a drawing that are in the selected state. Graphics can be added to the Selection collection by any number of methods:

• Graphic.Select
• GraphicSet.Select
• Graphics.Select (if the Graphics collection is the Drawing.Graphics, this selects all the graphics in a drawing)
• Selection.SelectByQuery

Whether the selection is added to or replaced by a selection operation is determined by the state of the Application.ReplaceSelection boolean property. When running the EXE (local) server, changing the contents of the selection automatically forces the Selection Tool to become active. Operations on Selection objects are the same as those permitted on a Graphics collection or a GraphicSet collection.

Picking

Picking is accomplished by the Viewport.Pick methods. Pick methods return a PickResult collection. To select all the graphics in a PickResult, use the PickResult.Select method. Each PickEntry in a PickResult contains a reference to a Graphic.

These Graphic objects can be analyzed independently and used (selected or put into a GraphicSet, for example) as necessary.

Low-level and High-level Graphic Methods

High-level methods closely mimic the TurboCAD user interface. High-level methods provide geometrical solutions: Line tangent to circle, etc. High-level methods create undoable actions without explicit programming. High-level methods are denoted in SDK by [...todo...] Low-level methods don't create undo records. Low-level methods allow fine-grained access to vertices, cosmetic attributes, etc. The programmer can create undo records through the UndoRecord object interface.

Undo Record Objects

TurboCAD has an undo system that is invoked by the user interface, as well as by high-level SDK methods (see high-level vs. low-level discussion). If you are using low-level SDK methods, you can create undoable actions by directly programming the methods of the UndoRecord object. UndoRecords are created and placed on a stack in the Drawing. The Drawing maintains a pointer into the stack.

Actions are undone by moving down the stack, or redone by moving up the stack. There are three typical scenarios to make an operation that modifies the graphics in a drawing undoable.

• Adding a new graphic to a drawing
  • Create a new UndoRecord object, using the Drawing.AddUndoRecord method.
  • Create or add the graphic to the drawing's Graphics collection, using either the Graphics.Add or Graphics.AddGraphic methods.
  • Put a reference to the newly added graphic in the UndoRecord object, using the UndoRecord.AddGraphic method.
  • Close the record, using the UndoRecord.Close method.
• Deleting an existing graphic
  • Create a new UndoRecord object, using the Drawing.AddUndoRecord method.
  • Put a reference to the graphic that is to be deleted in the UndoRecord object, using either the UndoRecord.DeleteGraphic or UndoRecord.RemoveGraphic method.
  • DeleteGraphic destroys the Graphic, while RemoveGraphic removes it from the drawing, and returns a copy.
  • Close the record, using the UndoRecord.Close method.
• Modifying the geometry or other properties of an existing graphic
  • Create a new UndoRecord object, using the Drawing.AddUndoRecord method.
  • Post the current state of the graphic to the UndoRecord, using the UndoRecord.PushGraphic method.
  • Modify the graphic using low- or high-level Graphic methods, such as setting the value of a Property owned by the graphic, relocating a vertex, etc.
  • Put a reference to the modified graphic in the UndoRecord object, using the UndoRecord.AddGraphic method.
  • Close the record, using the UndoRecord.Close method.

Customizing TurboCAD

Several types of "extension" objects exist to allow programmers to extend the core functionality of TurboCAD. Samples of how to create these objects and add them to the TurboCAD system are presented in the documentation. Regen method objects allow the creation and management of special graphic types that respond to changes in properties and geometry in a structured, algorithmic way ('smart' graphic behavior). Filter objects allow the importing and exporting of drawing data from and to new file types. Tool objects allow the creation of new toolbar buttons and menu items in the TurboCAD user interface, and permit the programmatically controlled modification of the layout of TurboCAD's menus and toolbars at runtime.

Previous Next

SDK Top API Reference TurboCAD Home Page TurboCAD Programming Forums